%
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\subsection{Drivers for Abs-Normal Form}
\label{absdrivers}
%
In this subsection we consider functions $y=F(x):\R^n \rightarrow \R^m$ that are non-smooth because of the occurrence of 
the absolute value function. The drivers provided generate a piecewise-linear 
approximation of the function $F$ in a point $x_0$ and first order derivatives of 
this second order approximation. The piecewise-linear model will be called piecewise 
linearization in the following. Further information about the piecewise linearization 
you can find in \cite{Griewank13}.

The piecewise linearization is given in \textit{abs-normal} form by 
\[ \left[\begin{array}{c}
          z\\y
         \end{array}\right]
   =\left[\begin{array}{c}
          c\\b
         \end{array}\right]      
    +\left[\begin{array}{cc}
          Z & L\\ J & Y
         \end{array}\right] 
    \left[\begin{array}{c}
          x\\|z|
         \end{array}\right].
\]
Here $z\in\R^s$ is a vector of $s\ge 0$ \textit{switching variables} and correspondingly 
the two vectors and four matrices specifying the function $F$ have the format
\[c\in\R^s,\quad Z\in\R^{s\times n},\quad L\in\R^{s\times s},\quad b\in \R^m,\quad J\in\R^{m\times n}, Y\in\R^{m\times s}.\]
The matrix $L$ is strictly lower triangular.

To compute the piecewise linearization $\Delta F(x_0;x)$ the abs-normal mode has to be 
enabled by using
\begin{tabbing}
\hspace{0.5in}\={\sf short int tag;} \hspace{1.1in}\= \kill    % define tab position
\>{\sf enableMinMaxUsingAbs()}
\end{tabbing}
before the $\mathit{trace\_on}()$ command.
If one is interested in the number $s$ of absolute value functions occurring in the function 
evaluation, one can get it by
\begin{tabbing}
\hspace{0.5in}\={\sf short int tag;} \hspace{1.1in}\= \kill    % define tab position
\>{\sf int get\_num\_switches(tag)}\\
\>{\sf short int tag;}         \> // tape identification 
\end{tabbing}
after tracing the function $F$.

In abs-normal mode several drivers are available. For a start there is a driver 
to evaluate $y=F(x)$. The driver also returns the values of $z$ which are the arguments 
of the intermediate absolute value functions. The evaluations of the absolute value 
function is interpreted as $|z_i|=\sigma_i*z_i$ with $\sigma_i=sign(z_i)$ in the zero 
order mode. The vector $\sigma\equiv \{-1,0,1\}^s$ is called signature vector.

\begin{tabbing}
\hspace{0.5in}\={\sf short int tag;} \hspace{1.1in}\= \kill    % define tab position
\>{\sf int zos\_an\_forward(tag,m,n,keep,x,y,z)}\\
\>{\sf short int tag;}         \> // tape identification \\
\>{\sf int n;}                 \> // number of independent variables $n$ and $m=1$\\
\>{\sf int m;}                 \> // number of dependent variables $m$\\
\>{\sf int keep;}              \> // flag for reverse mode preparation\\
\>{\sf double x[n];}           \> // independent vector $x$ \\
\>{\sf double y[m];}           \> // dependent vector $y=F(x)$ \\
\>{\sf double z[s];}           \> // argument of $\mathbf{abs}(z)$ 
\end{tabbing}
%
Additionally, there are drivers for the forward mode to evaluate first order 
derivatives of the piecewise linearization. For first order derivatives another 
signature vector generated by 
\begin{tabbing}
\hspace{0.5in}\={\sf short int tag;} \hspace{1.1in}\= \kill    % define tab position
\>{\sf int firstsign($z_i$, $Z[i]$)}\\
\>{\sf double z[s];}          \> // i-th component of argument of $\mathbf{abs}(z)$ \\
\>{\sf double Z[s][p];}          \> // i-th row of first derivative $Z=z\prime (x)X$
\end{tabbing}
has to be used. \textit{firstsign(u)} of a vector $u$ is defined as the \textit{sign()} 
of the first non-vanishing component of $u$ if that exists; otherwise the value is zero. 
More detailed information can be found in \cite{Griewank13}. 

\begin{tabbing}
\hspace{0.5in}\={\sf short int tag;} \hspace{1.1in}\= \kill    % define tab position
\>{\sf int fos\_an\_forward(tag,m,n,x0,x1,y0,y1,z0,z2)}\\
\>{\sf short int tag;}         \> // tape identification \\
\>{\sf int m;}                 \> // number of dependent variables $m$\\
\>{\sf int n;}                 \> // number of independent variables $n$\\
\>{\sf double x0[n];}          \> // independent vector $x$ \\
\>{\sf double x1[n];}          \> // tangent vector $x1$\\
\>{\sf double y0[m];}          \> // dependent vector $y_0=F(x_0)$ \\
\>{\sf double y1[m];}          \> // first derivative $y_1=F^\prime (x_0)x_1$\\
\>{\sf double z0[s];}          \> // argument of $\mathbf{abs}(z_0)$ \\
\>{\sf double z1[s];}          \> // first derivative $z_1=z_0^\prime (x_0)x_1$
\end{tabbing}

\begin{tabbing}
\hspace{0.5in}\={\sf short int tag;} \hspace{1.1in}\= \kill    % define tab position
\>{\sf int fov\_an\_forward(tag,m,n,p,x,X,y,Y,z,Z)}\\
\>{\sf short int tag;}         \> // tape identification \\
\>{\sf int m;}                 \> // number of dependent variables $m$\\
\>{\sf int n;}                 \> // number of independent variables $n$\\
\>{\sf int p;}                 \> // number of directions\\
\>{\sf double x[n];}           \> // independent vector $x$ \\
\>{\sf double X[n][p];}        \> // tangent matrix $X$\\
\>{\sf double y[m];}           \> // dependent vector $y=F(x)$ \\
\>{\sf double Y[m][p];}        \> // first derivative matrix $Y=F^\prime (x)X$\\
\>{\sf double z[s];}           \> // argument of $\mathbf{abs}(z)$ \\
\>{\sf double Z[s][p];}        \> // first derivative matrix $Z=z^\prime (x)X$
\end{tabbing}

In contrast to the drivers above the reverse mode does not require any directions. 
It always returns one row of the Jacobian matrix.

\begin{tabbing}
\hspace{0.5in}\={\sf short int tag;} \hspace{1.1in}\= \kill    % define tab position
\>{\sf int fov\_an\_reverse(tag,m,n,s,rownum,z)}\\
\>{\sf short int tag;}         \> // tape identification \\
\>{\sf int m;}                 \> // number of dependent variables $m$\\
\>{\sf int n;}                 \> // number of independent variables $n$\\
\>{\sf int s;}                 \> // number of sign switches\\
\>{\sf int rownum;}            \> // required row no. of abs-normal form \\
\>{\sf double z[n];}           \> // resulting adjoint value $z^T = u^T F^\prime (x)$\\
\end{tabbing}


% \bibitem{Griewank13}
% Andreas Griewank,
% {\em On stable piecewise linearization and generalized algorithmic differentiation}.
% Optimization Methods and Software 28(6):1139--1178, 2013.
